Custom Handlers, The Basics.
--------------------------------- -- -  -
The custom handler system allows you to specify the name of an external
public message port. This port will be sent messages whenever certain
things happen that you are interested in. Messages that are sent are
properly formatted ARexx messages.

An example code fragment to receive a message is:

        call waitpkt(myportname)        /* wait for messages to arrive */

        packet=getpkt(myportname)       /* get waiting message */
        arg0=getarg(packet,0)           /* get Argument 0 */
        arg1=getarg(packet,1)           /* get Argument 1 */
        arg2=getarg(packet,2)           /* get Argument 2, etc... */

        call reply(packet,0)            /* reply to the message */


Because of the multi-tasking nature of Opus 5, information custom handlers
receive can not be 100% relied on. For example, you may receive an "active"
message, but the cache that caused it may have immediately gone "inactive"
again. You should therefore check your port is clear of all messages before
processing any that have come in, and you should also use the
 lister query  command to make sure that things are how you expect them.
Also note that listers (unless you have turned  busy  on) can be closed by
the user at any time. An "inactive" message is sent when the lister is
closed. To check that a lister is still open, use the  lister query path 
command (or any other  query  command). If the lister no longer exists,
 RC  will contain the error code  XERR_INVALID_HANDLE  (10). Be aware,
though, that while these possibilities exist, generally they will not cause
a problem. For the most part it will only be if the user is
"playing around" that weird situations will occur.